OBP-TFTP extension

Open Firmware

Recommended Practice:

OBP-TFTP extension


Version: 0.5 Unapproved DRAFT


Published by the Open Firmware Working Group


April 23, 1996

Table of Contents

This document is a voluntary-use recommended practice of the Open Firmware Working Group. The Open Firmware Working Group is an ad hoc committee composed of individuals interested in Open Firmware as defined by IEEE 1275-1994, related standards, and their application to various computer systems.

The Open Firmware Working Group is involved both in IEEE sanctioned standards activities, whose final results are published by IEEE, and in informal recommendations such as this, which are published on the Internet at:

http://playground.sun.com/1275

Membership in the Open Firmware Working Group is open to all interested parties. The working group meets at regular intervals at various locations. For more information send email to:

p1275-wg@risc.sps.mot.com

Revision History

1. Introduction

The use of networks during booting becoming more common. Open Firmware does claim to support such network access. However, the base Open Firmware document ([1]) is very terse in its description of the obp-tftp support package; it only mentions the use of TFTP ([2]) and does not even explicity reference BOOTP ([3]). Platform bindings have added requirements for BOOTP, but have not explicitly documented details of the expected support of the obp-tftp package or of the required methods of "network" devices beyond the open, close and load methods.

The specifications contained herein are based upon RFCs (Request For Comments) published by the Internet Engineering Task Force and existing practice in Open Firmware implementations.

1.1. Purpose

This document adds specific requirements for the Open Fimrware obp-tftp support package, the Open Firmware user interface and drivers for "network" devices.

1.2. Scope

The specifications for the obp-tftp package and user interface contained within this document are recommended for all Open Firmware implementations. The requirements on "network" device drivers are recommended for all "network" devices, including plug-in cards.

2. References and Definitions

2.1. References

[1] IEEE Standard for Boot (Initialization Configuration) Firmware: Core Requirements and Practices, published by IEEE.

[2] RFC 1350, TFTP Revision 2, published by IETF.

[3] RFC 951, Bootstrap Protocol (BOOTP), published by IETF.

[4] RFC 768, User Datagram Protocol, published by IETF.

[5] RFC 1542, Clarifications and Extensions for the Bootstrap Protocol, published by IETF.

[6] RFC 826, An Ethernet Address Resolution Protocol, published by IETF.

[7] RFC 792, Internet Control Message Protocol, published by IETF.

2.2. Definitions

3. "network" booting

The base document ([1]) describes the use of TFTP ([2]) for booting over a network. However, it is often the case that TFTP can not be used directly because the booting system does not necessarily "know" the proper file to be loaded or event an appropriate server from which to request the file.

The BOOTP protocol ([3]) is an IETF standard that defines a mechanism by which a booting device that does not know "anything" can locate a server, determine its proper IP address and identify the appropriate file that can be loaded.

BOOTP allows for a range of system knowledge to be used in the process. At one extreme, the booting device knows nothing except for its network hardware address (e.g., its 6-byte EtherNet address). At the other end of the spectrum, the booting device can know the server's IP address, its own IP address, any gateway necessary, etc. The open method arguments described below allow the user (via command-line and/or boot-device arguments) to specify the various pieces of knowledge.

3.1. BOOTP overview

The BOOTP mechanism relies on the transmission of UDP ([4]) packets using well-known ports; port 67 is used as the "server" port and port 68 is used as the "client" (i.e., booting system's) port .

This document will refer to several fields within the BOOTP protocol's packet format. These fields are:

op1=BOOTREQUEST, 2= BOOTREPLY

ciaddrclient's IP address (the booting system)

yiaddr'your' (i.e., client) IP address (filled in by server)

siaddrserver's IP address

giaddr'gateway' IP address

chaddrclient's hardware address

fileboot file name

Note: this document does not go into complete details of the BOOTP or TFTP protocols. For complete details, refer to [3] , [5] and [2].

3.2. Example of "network" booting

A common case of booting via "network" device is one in which the booting system knows nothing about the booting environment, including its own IP address. In this case, the client creates a BOOTREQUEST packet with zeros in the ciaddr, yiaddr, siaddr, giaddr and file fields (thus, indicating that it doesn't know what they should be) and fills in the chaddr field with the client's hardware address that is assumed to be known. The siaddr field is filled with 255.255.255.255 that indicates a "broadcast" IP address; i.e., all potential servers should look at the packet.

The client then broadcasts (i.e., using a network-specific broadcast hardware address) the BOOTREQUEST packet. Potential servers examine the packet to determine if they should respond to the request. This is typically done by consulting a table, indexed by the chaddr field.

A server that determines that it should respond does so by creating a BOOTREPLY packet filling in the yiaddr field with the proper IP address of the client and the file field with the filename of the "boot-image" appropriate for the system and sending the packet to the client.

The client examines the BOOTREPLY packet and uses the yiaddr field as its IP address for subsequent transmissions and the siaddr field as the IP address of its client. It also uses the file field of the reply packet as the filename to be used for the TFTP request that it will generate.

At this point, the client may know all the information necessary to attempt to load the boot-image file. The one piece of information that is not explictly handled by the BOOTP protocol is obtaining the hardware address of the server. If the client can obtain the server's hardware address (HA) by access to the hardware header of the BOOTREPLY packet, then it can use that as the server's HA.

However, it may be necessary to use ARP ([6]) to map the IP address of the server to its HA.

Once it has obtained all of the relevant information about itself and its server, the client loads the boot-image. It starts this process by sending a TFTP read request (RRQ) packet, using the filename obtained from the BOOTREPLY packet. This RRQ packet is sent to the server at its proper HA and IP address obtained during the BOOTP process.

Assuming that the RRQ is successful, the server will reply with a TFTP DATA packet. The loading process then proceeds with a sequence of ACK replies sent by the client and DATA packets sent by the server. The process ends when the length field of a DATA packet is 0, indicating the the entire file has been sent.

Since UDP is not a reliable protocol, and since a server may not be found, the actual BOOTP (and, subsequent TFTP loading) process contains timeout and retry provisions that were ignored above so that the basic data flow could be simply described.

3.3. BOOTP options

The above example is a typical case for booting a client. However, the BOOTP protocol allows various alternatives by allowing the client to fill in more details in its initial BOOTREQUEST packet. For example, the client may know what server it wishes to use (i.e., its IP number), or it may know what file it wants to load from any server that can supply it.

The description of the arguments for the open method of the obp-tftp package describe how these various alternatives can be specified.

Additional methods are defined within the obp-tftp package to report the values of BOOTP parameters that apply to an opened instance. These paramaters can be obtained by a "network" device and remembered (e.g., in static values) so that a Client program can obtain them later. An example of where this would be done is when a boot image has been loaded by the "network" device and that boot program needs to get back to the particular server for additional files.

4. PING command and methods

Users of networks often need to know the if the network path to a node is working. The "standard" way of doing this is by means of a "ping" command that is usually available from operating systems that provide network access. This ping command uses the ICMP ([7]) protocol to send an ECHO message (using a hardware broadcast) to the IP address of the target. The target, assuming that the network path and the target are functioning, sends an ECHO REPLY packet back to the node that sent the original ECHO request.

The description of the ping user interface command and the ping methods in the "network" device and obp-tftp package show how this facility can be provided by an Open Firmware implementation.

5. Additional requirements for the OBP-TFTP support package.

This section describes methods that must be provided the obp-tftp support package. The open method is required by the base document ([1]), but details are missing from that description and new requirements for argument parsing are added by this document. The ping method is new.

5.1. arguments to the obp-tftp open method

The open method of the obp-tftp support package shall support the following arguments:

siaddr,filename,ciaddr,giaddr,subnet-mask,bootp-retries,tftp-retries

The external format of the siaddr, ciaddr, giaddr and subnet-mask fields are in Internet-standard "dotted-decimal" notation.

siaddr is the IP address of the intended server. If this field is specified, its decoded value is used for as the siaddr field of the BOOTREQUEST packet (and subsequent TFTP packets). If this field is not specified, the value of 0.0.0.0 is used for the siaddr field of the BOOTREQUEST packet, and the server's IP address is determined by the siaddr of the BOOTREPLY packet. The server's IP address is saved so that it can be reported by the si-addr method.

filename is the filename of the file that is to be loaded by TFTP from the server. If specified, the file field of the BOOTREQUEST field is set from this field; if not specified, the file field is set to zero. Since this filename may be a "generic" name, the file field of the BOOTREPLY packet is used as the Filename field of the RRQ packet during the subsequent TFTP loading.

If the the filename is not specified or is not the string "%NONE%", the obp-tftp open method will attempt to initiate the reading of the file (as determined by the file field of the BOOTREPLY) by issuing a TFTP RRQ packet. If this succeeds, the file can be subsequently loaded, and the open will report success.

The special filename argumnent of "%NONE%" is used to specify that no TFTP process is to follow the open. This is used to open the obp-tftp package and obtain IP addresses, subnet-mask, etc., but without a TFTP RRQ packet. The purpose of this is so that methods other than load (e.g., ping) can be performed on the open instance of obp-tftp.

ciaddr is the IP address of the client (i.e., the system being booted). If this field is specified, its decoded value is used as the ciaddr field of the BOOTREQUEST packet (and, subsequent TFTP transactions); i.e., the yiaddr field of BOOTREPLY packets is ignored. If this field is not specified, the ciaddr field is set to 0.0.0.0 and the client's IP address is determined from the yiaddr field of the BOOTREPLY packet. (Note: this behavior is specified by [5].) In either case, the ciaddr that is being used by this instance shall be remembered and supplied as the result of a subsequent ci-addr call.

giaddr is the IP address of the BOOTP 'gateway'. (Note that this is not necessarily the same as the network gateway; see [3] and [5] for details.) If this field is specified, its decoded value is used as the value of the giaddr field of the BOOTREQUEST packet; if not specified, the giaddr field of the BOOTREQUEST packet is set to 0.0.0.0. The value that applies to the current instance is remembered and supplied as the result of the gi-addr call of this open instance.

subnet-mask is the subnet-mask to be used for this interface.

[[[Author's note: section on subnet-mask needs more work]]]

bootp-retries is the maximum number of retries that are attempted before the BOOTP process is determined to have failed. I.e., if, after bootp-retries attempts at transmission of a BOOTREQUEST packet are made with no responding BOOTREPLY packets are received, the obp-tftp package shall report failure by returning a non-zero value as its open result.

tftp-retries is the maximum number of retries that are attempted before the TFTP process is stopped. The retries count shall include timeouts and bad DATA packets. If the count is exceeded, the TFTP load method shall abort.

5.2. Additional methods for the obp-tftp package

The following methods report the values of various BOOTP values that apply to the currently open instance of obp-tftp. These values may have been supplied on the open as arguments or may have been acquired through the BOOTP protocol.

ci-addr( -- ip-addr )S

Standard method to report the IP address of this interface.

The ip-addr returned is the IP address to be used for this device.

si-addr( -- ip-addr )S

Standard method to report the IP address of the server.

The ip-addr returned is the IP address of the server.

gi-addr( -- ip-addr )S

Standard method to report the IP address of the gateway.

The ip-addr returned is the IP address of the gateway. A value of 0.0.0.0 implys that no gateway is involved.

subnet-mask( -- mask )S

Standard method to report the subnet-mask of this intance.

The value is the subnet-mask to be used.

The following call is used by a "network" device's ping method to attempt a single ping.

ping( msecs -- reply? )S

Standard method to attempt an ICMP echo.

The msecs value is the time to wait (in millisecondss) after an ICMP echo request before reporting failure. The reply? result is true if a reply to the echo was seen, otherwise reply? is false.

6. Additional requirements for "network" devices

6.1. Additional properties for "network" devices

The following additional properties shall be reported by packages representing "network" devices to be compliant with this recommended practice.

"network-type"S

prop-name, standard property to report type of "network".

prop-encoded-array, a string, encoded as with encode-string, that is chosen from the following set: "enternet", "ethernet-802.3", "ethernet-fast", "token-ring".

"cable-type"S

prop-name, standard property to report type of cable of "network".

prop-encode-array, a string, encoded as with encode-string, that is chosen from the following set: "aui", "bnc", "10baseT".

6.2. Additional methods for "network" devices

The following methods shall be supported by "network" devices that are compliant with this recommend practice.

The following methods report the values that apply to the last use of the device. I.e., after using the device to load a boot image, these methods recall the BOOTP parameters that applied.

ci-addr( -- ip-addr )S

Standard method to report the IP address of this interface.

The ip-addr returned is the IP address to be used for this device. If ip-addr is 0, then the IP address of this interface has not yet been determined.

si-addr( -- ip-addr )S

Standard method to report the IP address of the server.

The ip-addr returned is the IP address of the server. If ip-addr is 0, then the IP address of the server not yet been determined.

gi-addr( -- ip-addr )S

Standard method to report the IP address of the gateway.

The ip-addr returned is the IP address of the gateway. If ip-addr is 0, then the IP address of the gateway has not yet been.

subnet-mask( -- mask )S

Standard method to report the subnet-mask of this interface.

The value is the subnet-mask to be used for this device. If the returned mask value is 0, then the subnet-mask has not yet been determined.

The following method is an entry to provide access to the obp-tftp package's ping support.

ping( ip-addr nattempts msecs -- nreplies )S

Standard method to support the ping user interface command.

This method is a "pass-through". I.e., it shall open an instance of the obp-tftp package with a filename field of "%NONE%", using ip-addr as the siaddr and nattempts as the bootp-retries value. If the open fails, the nreplies return value is -1. If the open is successful, nattempts calls of the open obp-tftp instance's ping method are done, using msecs as the msecs argument. The number of successful attempts is kept track of. When all attempts have been made, the obp-tftp instance is closed and the number of successful attempts is reported.